Gareth's style guide
Gareth Rees, April 1996.
- Present coherent articles as a whole
- Make sure deep structure is accessible
- Give an impression of the size of your database
- Distinguish internal and external links
- Never use your home page as the startup page for your browser
- Don't use links as footnotes
- Annotate your references
- Don't discuss your own pages
- Other style principles
This material is intended to supplement the CERN
Style Guide, not to replace it. Some of it is appropriate to people
with big databases of material to organise, other bits are directed at
people with lame personal home pages.
Readers understand coherent articles - they see them all the time in
magazines, newspapers, journals, conference proceedings and so on. They
don't have much experience of reading articles that have been chopped
into pieces - and just as importantly, neither do you. If you choose to
present your information in a form close to existing forms, then you
know what is successful in that form and what isn't. If you choose to
adopt a new form, then you had better think very carefully about exactly
how to structure your text for best effect. Read the literature on
hypertext for discussion of how to structure documents for readability;
test your documents on readers as though they were computer programs
with strange new user interfaces (which, in a sense, they are).
In most browsers, it's easier to navigate within a page than between
pages. Dividing a single text into a number of pages means your readers
will have to issue a lot of navigational commands to read it.
At the current state of the Internet, connecting to a site that's
distant from you tends to be slow. If you chop your material into small
pages, then readers are prevented from following the thread of your
argument because of the long wait for each paragraph to download. If
your material is presented in one article, then the initial wait is
longer, but once the article has been downloaded the reader can give it
their full attention.
If you have space, the best solution may be to take advantage of the
medium of hypertext and present your article in both ways (as a single
complete article, and as a multiplicity of paragraphs), and let the
reader choose, depending on their preference.
In a deep hypertext structure, with indexes at several levels, it is
possible for information to be `lost' in the sense that a reader reading
the toplevel index will be unaware of the existence of that
information.
This is most likely to happen if different levels of index organise
their information according to different criteria. For example, suppose
that a hypothetical university information server has a home page which
indexes the home pages of the departments in that university, but
doesn't say what information those departments provide. In such a case,
you have to guess which department has the information you need before
you can find it.
It is therefore important to provide clues at each level indicating what
is to be found on each of the branches. Hierarchical subject trees are
examples where this works, because the choices at each level provide
access to subsets of the subjects named at the level above.
A real example, just in case you think I'm making this all up: try to
find the information about free Esperanto lessons starting at the Cambridge University Computing
Service.
Having a clear index structure helps you to:
A good way to prevent your readers getting `lost in hyperspace' (a
common feeling when browsing a complex structure) is to give them plenty
of clues as to how big your database is.
The best clue you can provide is a complete listing of entries (even if
such a list isn't appropriate on the home page, it can be provided
separately). A top-level index of categories should annotate each entry
with the number of documents to be found by following that entry. If
you can find an appropriate visual organising principle, then a
graphical overview might help those of your readers with fast
connections, graphical browsers and colour monitors.
In order to give a correct impression of the size of your database, you
need to:
Some `home pages' freely mix links pointing to documents in the database
at that site with documents stored elsewhere, as though the Web were a
single amorphous information resource. But amorphous doesn't
necessarily imply useful.
If you maintain a personal home page, then to accomplish this, you
should:
The startup page for a browser is a place where you put all the links
you use regularly, especially including the major libraries and
metaindexes on the Web. On the other hand, your home page is a
document that describes you to the rest of the world, and lists the
resources that can be found in your database. So why confuse the two?
Footnotes distract from a line of argument; if the material in a
footnote can't be integrated into the body of the text, then it probably
doesn't belong in a footnote, either. Just because you can
include jottings, notes, side issues and other material in a hypertext
document, doesn't mean you have to.
Please, annotate your lists! Try to provide a short description of the
contents of the destination of the link (but use your discretion; some
titles are self explanatory and won't need annotating, and an annotation
that says nothing useful is as bad as no annotation at all). Think of
it as your way of adding value to the list: anyone can compile a list of
links (the webcrawling robots have databases with hundreds of
thousands of URLs) but you have to read and understand the documents in
order to write useful descriptions, and thus make your list a valuable
resource.
Bryan
O'Sullivan's bibliography is excellent in this respect.
The mere lack of anything to say doesn't stop some people; instead of
writing about the world `out there', they discuss their own Web pages -
how they were written, when they were written, what's new about them,
what their friends had to say about them, what the usage statistics are,
who's read them, and so on.
Mostly from Jutta
Degener.
- Keep to the subject (don't fall into the `provider' role).
- Be specific in anchor texts (don't use `next', `prev', `back', `here').
- Links stress the phrases they are anchored to (so watch out for
consequent clunkiness).
- Plan for search engines (use robots.txt).
- Choose durable filenames.
- Never say `click' or assume your readers have a particular browser.
- Make the document readable if taken out of context (e.g., by
printing it).
- Choose as shallow a structure as possible.
- Present information in several ways if appropriate (you can have a
home page, a table of contents, a graphical overview and an
index).
- Provide a title page for multipart documents.
[Email: Gareth.Rees@cl.cam.ac.uk]
[Up: Gareth Rees]
[Prev: Film reviews]
[Next: Short essays on science fiction and other books]